Setting up an Oracle Environment with Windows Docker Desktop

TLDR

• Oracle no longer provides pre-built Docker Images for direct download; you must download the Dockerfile from GitHub and build it manually.
• A Linux Bash Shell (such as Git Bash or WSL) is required in the Windows environment.
• If you encounter MD5 checksums errors during image building, add the -i parameter to skip the check.
• If you encounter an error stating that the image does not exist during the build process, check the FROM oraclelinux tag in the Dockerfile; it is recommended to update it to 7-slim if it is too old.
• Versions 12c and above use the CDB/PDB architecture. When creating users, you must switch to the PDB and use SERVICE_NAME for connections.
• If custom users appear to be missing after the container starts, it is usually because the PDB is mounting slowly; please wait patiently.
• Based on testing, 11g and 12c XE versions are prone to folder permission issues on Windows; it is recommended to prioritize using the 19c SE2 version.

Environment Setup and Image Creation

When to encounter this issue: When you need to install an Oracle database, but there are no official pre-built images on Docker Hub.

Since Oracle has stopped providing images for direct download, you must build them using resources from Oracle GitHub. In a Windows environment, ensure that Git Bash or WSL is installed to execute Linux Shell commands.

Build Steps and Notes

1. After downloading the Dockerfile for the corresponding version, enter the directory and execute the build command: ./buildContainerImage.sh -v [version] -t [image_name:tag] [-e | -s | -x] [-i] [-o]
2. Handling MD5 errors: If an MD5 checksums error occurs during execution, add the -i parameter to the end of the command to ignore the check.
3. Handling 'Image does not exist' errors: If the build fails and indicates that the image does not exist, open the Dockerfile to check the tag following the FROM instruction (e.g., oraclelinux), and verify if that tag exists on Oracle Docker Hub. It is recommended to update it to 7-slim.

Container Deployment and Configuration

When to encounter this issue: When the image build is complete and you need to start the service via Docker Compose.

Please use the following template to create docker-compose.yml:

version: '3.7'

services:
  TP-Oracle:
    image: oracle/database:{image tag}
    container_name: TP-Oracle
    ports:
      - 1521:1521
      - 5500:5500
      - 8080:8080
    volumes:
      - {local oradata}:/opt/oracle/oradata
      - {local scripts/startup}:/opt/oracle/scripts/startup
      - {local scripts/setup}:/opt/oracle/scripts/setup
    restart: always
    environment:
      - ORACLE_PWD={your password}
      - ORACLE_CHARACTERSET=AL32UTF8

TIP

Container startup takes a long time. Please check the logs via the Docker Dashboard to monitor the initialization progress.

Database User Management and PDB Switching

When to encounter this issue: When using version 12c or higher, you may be unable to log in directly or find users due to the CDB/PDB architecture.

If you encounter an ORA-01017: invalid username/password error, please follow these steps:

1. Execute show pdbs to view the PDB name (usually ORCLPDB1 or XEPDB1).
2. Execute ALTER SESSION SET CONTAINER={queried name} to switch to the PDB.
3. Re-create the user and permissions within the PDB.
4. When connecting, be sure to use SERVICE_NAME={PDB Name} instead of SID.

Common Issues and Troubleshooting

Folder Permission Anomalies

In Windows environments, 11g and 12c XE versions often experience folder permission errors, causing the container to fail to run properly. Based on testing, the 19c SE2 version operates more stably on Windows.

Missing User Issue

If you find that a newly created user has disappeared after restarting your computer or Docker, it is usually because the PDB database is mounting slowly. Please wait for a period of time until the database has fully started, and it will return to normal.

Change Log

• 2022-10-24 Initial document created.